home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / C / Frameworks / Recursive Shell 1.0.1 / readme.txt
Text File  |  1996-06-17  |  6KB  |  175 lines
  1. /*
  2.  
  3. Recursive Shell        v1.0.1    17 June 1996
  4. © 1996 Theron Trowbridge
  5.  
  6. e-mail:        theron@aimla.com
  7.             -or-
  8.             Tmonk@concentric.net
  9.             
  10. snail-mail:    3685 Jasmine Ave. #19
  11.             Los Angeles, CA 90034
  12.  
  13.  
  14. What Is This?
  15.  
  16.     this is a CodeWarrior 7 project which creates a shell application that
  17.     makes it easy to create utility applications that perform some task to a
  18.     large number of files.
  19.     
  20.     It supports drag-and-drop - simply drag files or folders to the icon and
  21.     the application does to each what it wants.  In the case of folders, it
  22.     searches recursively through them and performs the same on each file/
  23.     folder inside.  You can also start the whole process from the menus after
  24.     launching the application, of course.
  25.     
  26.     It is easy to create new utility applications - you simply fill in the
  27.     functionality of a few routines in one file, and it's done.
  28.     
  29.     The applications require System 7 or better. 
  30.  
  31.  
  32. Who Is It For?
  33.  
  34.     I have, in the past, needed programs which can do what this shell does,
  35.     but have been unable to find them.  These are pretty specific tasks I
  36.     needed them for, so it is unsurprising programs didn't already exist for
  37.     them.
  38.     
  39.     But all of these things need a similar framework into which I would want
  40.     to simply drop in small bits of functionality.  That is where the idea for
  41.     this shell started.
  42.     
  43.     This is really for anyone who also has need for a small utility which can
  44.     do some fixed action on every file in a folder, or simply on a whole mess
  45.     of files.  If the task you need to do is simple, your new utility can be
  46.     done in just a few minutes!
  47.  
  48.  
  49. The Legal Stuff
  50.  
  51.     This code is ©1996 Theron Trowbridge.  It is offered without warranty to
  52.     its correctness, functionality, or usefulness, and I cannot be held
  53.     responsible for what you do with it, or any damage it may cause either
  54.     through improper use or a mistake on my part.  In other words, use at your
  55.     own risk.
  56.     
  57.     You are free to use this code, but the portions of the code I wrote remain
  58.     my copyright, so there are a few restrictions:
  59.     
  60.     You may not distribute the result of this code as a commercial product
  61.     without my consent.  Just ask - I'm likely to give it.
  62.     
  63.     With the exception on CD-ROM (or other commercial) collections, this code
  64.     may be distributed freely, as long as it is in original form and all
  65.     associated files (including this notice) are included in unmodified form.
  66.     
  67.     Permission is hereby granted for Celestin Company, Inc. (for the Apprentice
  68.     CD-ROM), Pacific HiTech (for the Info-Mac CD-ROM) and the Arizona Macintosh
  69.     User Group (For the BBS In A Box CD-ROM) to include this package in CD-ROM
  70.     collections, provided a copy of the CD-ROM is provided to me for free or at
  71.     a nominal cost.
  72.     Other CD-ROM collections will almost certainly receive my permission for
  73.     inclusion.  Just contact me first, and give me a copy of the disc when
  74.     published.
  75.  
  76.  
  77. How To Use It
  78.  
  79.     To create a new application, do the following:
  80.     (Almost all of these are optional - only the first and last are essential)
  81.     
  82.         1 -    Make a copy of the project folder and rename it to whatever name
  83.             you've chosen for your new application.
  84.             
  85.         2 -    Change the name of the two project files (Recursive Shell (68k).µ
  86.             and Recursive Shell (PPC).µ) to reflect the name you've chosen.
  87.             
  88.         3 - Change the PICT resource (ID 700) in the file Recursive Shell.rsrc
  89.             to a splash screen for your application.
  90.             
  91.         4 -    Change text of About... item in the Apple Menu resource (ID 700)
  92.             to reflect the name you've chosen for your application.
  93.             
  94.         5 - Change the name of Recursive Shell.rsrc to reflect the new name.
  95.         
  96.         6 -    In each project, add your newly-named resource file and remove the
  97.             old one.
  98.             
  99.         7 -    In each project's project preferences, change the output file name
  100.             to the new name.
  101.             
  102.         8 -    Add your routines to DoStuff.c file: InitializeStuff(), DoToEachFile(),
  103.             DoToEachFolder(), DoToSelFolder(), and DeInitializeStuff().
  104.             
  105.         9 -    Make your new project.
  106.         
  107.     You can actually skip all of these steps, except for the last.  You should
  108.     make a copy of the project file, though.  You can do as many or as few of
  109.     these as you like.
  110.     
  111.     If you do skip these steps, the application name, about box, and About...
  112.     menu item will be the default ones I've created.  Oh, yeah - and it will
  113.     recurse through folders and files, but it won't actually do anything to
  114.     them.
  115.     
  116.     You can also change the icon (which is pretty ugly, I admit).  Simply
  117.     paste your new one into the Get Info... box in the finder.  If you want to
  118.     make it more permanent than that, you should pick a new Creator code (and
  119.     register it with Apple - I already registered 'RCSH' which this one uses)
  120.     to avoid icon conflicts.
  121.     
  122.     
  123.     There are two sample applications which were created with this shell
  124.     included in this package: ListFiles (which creates a text file containing
  125.     the full pathname of each file processed) and Count Items (which counts the
  126.     number of files and folders processed and tells the user).
  127.  
  128.  
  129. Known Problems
  130.  
  131.     Because of the way the items in a folder are read, if the program deletes
  132.     any of the files, it will later trip up and run out of items.  This will
  133.     be fixed in the next version.
  134.     
  135.     DoToSelFile() in DoStuff.c is never called.  It is there for balance with
  136.     the DoToSelFolder() routine, but if you drop a file on the icon, it just
  137.     calls DoToEachFile().  Should be removed.
  138.  
  139.     
  140.     If you find any other bugs or unusual behavior, please let me know and I
  141.     will fix it.
  142.     
  143.  
  144. Features For Future Versions
  145.  
  146.     More intelligent parsing of files (see Known Problems).
  147.     
  148.     A preferences file which keeps track of the following:
  149.         Recurse into sub-directories?
  150.         Resolve aliases?
  151.     These will be options in future versions, and they will be automatically
  152.     read from the preferences file.  There will be a standard preferences
  153.     interface to set them.
  154.     
  155.     Preferences API to allow the application to store its own preferences in
  156.     the preferences file.
  157.  
  158.     A confirmation for aborting the process.
  159.     
  160.     A progress dialog box will be added, with possible pre-calcuation of
  161.     numbers of files for an accurate progress bar.
  162.  
  163.     A nicer busy cursor (animated or something).
  164.     
  165.     Allow the user to select anything, not just a folder when selecting
  166.     Open... item in the File Menu.
  167.     
  168.     
  169.     Send me e-mail or snail mail and I will keep you on a list to receive
  170.     free updates of the shell when they become available.   Comments and
  171.     suggestions also welcome.
  172.  
  173.  
  174.  
  175. */